<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>Event Manager</title>
</head>
<body>
<h3>Event Manager</h3>
<p><h4>About</h4>
The aspectjutil-eventmanager is an event manager framework by AspectJ.<br />
Started from the inspiring idea found in the blog article: <a href="http://www.aspectprogrammer.org/blogs/adrian/2005/03/event_driven_ar.html"
>Event Driven Architecture by adrian</a> to use AspectJ's <code>pertypewithin</code> and 
<code>aspectOf</code> to track the event listener instance.<br />
<br />
<a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/EventListenerInstanceTracker.html"
><code>EventListenerInstanceTracker</code></a> class is for tracking event listener instance(s) and <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/EventHandler.html"
><code>EventHandler</code></a> class is for bridging between eventer and event listener. 
<ul>
	<li>The <b>eventer</b> is either invocation of member method or value change on member field marked with 
		<a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/label/EventTrigger.html"
		><code>@EventTrigger</code></a> annotation. 
	</li>
	<li>The <b>event listener</b> is method (marked with <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/label/PreEvent.html"
	><code>@PreEvent</code></a> annotation and/or <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/label/OnEvent.html"
	><code>@OnEvent</code></a> annotation) of the event listener object annotated with <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/label/EventListener.html"
	><code>@EventListener</code></a>. </li>
</ul>
</p>
<p><h4>Usage guide</h4>
<ol>
	<li>Create an event class for your event.<br />
		For now, let's say it's <code>DemoEvent</code> class. 
	</li>
	<li>Regarding <b>eventer side</b>, add <code>@EventTrigger</code> annotation to your eventer method 
		or field.
		<ul>
			<li>To let the <u>execution of a method trigger <code>DemoEvent</code> event</u> then:
				<blockquote>
					<code>
						public class DemoEventer {<br />
						&nbsp;&nbsp;&nbsp;&nbsp;<b>&#64;EventTrigger( DemoEvent.class)</b><br />
						&nbsp;&nbsp;&nbsp;&nbsp;public void triggerDemoEvent() {<br />
						&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...
					</code>
				</blockquote>
				Putting <code>@EventTrigger</code> annotation is supported regardless visibility and 
				static/non-static of the eventer method.
			</li>
			<li>To let the <u>value change of a member field trigger <code>DemoEvent</code> event</u> then:
				<blockquote>
					<code>
						public class DemoEventer {<br />
						&nbsp;&nbsp;&nbsp;&nbsp;<b>&#64;EventTrigger( DemoEvent.class)</b><br />
						&nbsp;&nbsp;&nbsp;&nbsp;private AnyType fieldTriggerDemoEvent;<br />
					</code>
				</blockquote>
				Adding <code>@EventTrigger</code> annotation is supported regardless visibility and 
				static/non-static of the eventer field. 
			</li>
		</ul> 
	</li>
	<li>Regarding <b>event listener side</b>
		<ol>
			<li>Put <code>@EventListener</code> annotation to the event listener class.
				<blockquote>
					<code>
						<b>&#64;EventListener</b><br />
						public class EventRecipient {<br />
						&nbsp;&nbsp;&nbsp;&nbsp;...
					</code>
				</blockquote>
			 	If the event listener instance of the <code>EventRecipient</code> class in this example 
			 	is known to be no longer necessary when any other object has no reference to it, then 
			 	you can give <code>EventListener.gcSubject()</code> attribute <code>true</code>, in order 
			 	to avoid memory leakage. 
			</li>
			<li>Put <code>@PreEvent</code> and/or <code>@OnEvent</code> annotation to event listener 
				method.<br />
				Your event listener method must have the single argument of <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/EventInfo.html"
				><code>EventInfo</code></a> type. 
				<ul>
					<li><b>To get the listener method executed after the event occurrence</b>, 
						then use <code>@OnEvent</code> annotation.
						<blockquote>
							<code>
								<b>&#64;OnEvent( value={DemoEvent.class})</b><br />
								void onDemoEvent( <b>EventInfo</b> eventInfo) {<br />
								&nbsp;&nbsp;&nbsp;&nbsp;...
							</code>
						</blockquote>
					</li>
					<li><b>To get the listener method executed before the event occurrence</b>, 
						then use <code>@PreEvent</code> annotation.
						<blockquote>
							<code>
								<b>&#64;PreEvent( value={DemoEvent.class})</b><br />
								void preDemoEvent( <b>EventInfo</b> eventInfo) {<br />
								&nbsp;&nbsp;&nbsp;&nbsp;...
							</code>
						</blockquote>
					</li>
					<li>When your listener method needs <u>to subscribe to multiple different events</u>, 
						then provides those event classes delimited with ','. 
						<blockquote>
							<code>
								&#64;OnEvent( <br />
								&nbsp;&nbsp;&nbsp;&nbsp;value={<b>DemoEvent1.class,DemoEvent2.class</b>})<br />
								void onDemoEvent( <b>EventInfo</b> eventInfo) {<br />
								&nbsp;&nbsp;&nbsp;&nbsp;...
							</code>
						</blockquote>
					</li>
					<li>By default, the event listener method will be invoked only when the listening 
						event is triggered by the eventer object instantiated within the same thread what 
						is also instantiated the event listener object.<br />
						To let the event listener method executed by the event triggered by the eventer 
						object instantiated in other thread than one instantiated the event listener 
						object, give false to <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/label/OnEvent.html#amongInstancesInThread()"
						><code>OnEvent.amongInstancesInThread()</code></a> attribute or/and <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/label/PreEvent.html#amongInstancesInThread()"
						><code>PreEvent.amongInstancesInThread()</code></a> attribute. 
					</li>
					<li>To set the execution order among the event lister methods, use <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/label/OnEvent.html#orderForEachEvent()"
						><code>OnEvent.orderForEachEvent()</code></a> attribute or/and <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/label/PreEvent.html#orderForEachEvent()"
						><code>PreEvent.orderForEachEvent()</code></a> attribute.
						<blockquote>
							<code>
								&#64;OnEvent( <br />
								&nbsp;&nbsp;&nbsp;&nbsp;value={<b>DemoEvent1.class,DemoEvent2.class</b>}, <br />
								&nbsp;&nbsp;&nbsp;&nbsp;<b>orderForEachEvent={0,3}</b>)<br />
								void onDemoEvent( <b>EventInfo</b> eventInfo) {<br />
								&nbsp;&nbsp;&nbsp;&nbsp;...<br />
							</code>
						</blockquote>
						In that example case, among the event listener methods, the <code>onDemoEvent</code> 
						method will have the turn zero (first execution order) for 
						the <code>DemoEvent1</code> event and the turn 3 (fourth execution order) for 
						the <code>DemoEvent2</code> event.<br />
						For more information regarding other criterion of the execution order among 
						the event listeners, refer to <a href="apidocs/com/newmainsoftech/aspectjutil/eventmanager/SubscriberMethodUnitComparator.html#compare(com.newmainsoftech.aspectjutil.eventmanager.SubscriberMethodUnit,%20com.newmainsoftech.aspectjutil.eventmanager.SubscriberMethodUnit)"
						><code>SubscriberMethodUnitComparator.compare</code></a> method JavaDoc.  
					</li>
				</ul>
			</li>
		</ol>
	</li>
</ol>
</p>
<p><h4>Configuration guide</h4>
<ol>
	<li>Make your project a AspectJ project.</li>
	<li>Add aspectjutil-eventmanager.jar to AspectJ's aspect path.</li>
</ol>
</p>
</body>
</html>